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ABOUT THIS CHAPTER 


This chapter describes the Operating System Utilities, a set of routines and 
data types in the Operating System that perform generally useful operations such 
as manipulating pointers and handles, comparing strings, and reading the date 
and time. 


Depending on which Operating System Utilities you're interested in using, you 
may need to be familiar with other parts of the Toolbox or Operating System; 
where that's necessary, you're referred to the appropriate chapters. 


Because in the 128K ROM there can be both an Operating System trap and a Toolbox 
trap for any given trap number (for details, see the Using Assembly Language 
chapter), two variants of GetTrapAddress and SetTrapAddress have been added. 
These new routines, NGetTrapAddress and NSetTrapAddress, require you to specify 
whether the given trap number refers to an Operating System trap or a Toolbox 
trap; the following data type is defined for this purpose: 


TYPE TrapType = (OSTrap,ToolTrap) ; 


The RelString function fills the need for a full-magnitude, language- independent 
string comparison, particularly in the hierarchical file system, where entries 
are sorted in alphabetical order. Whereas the EqualString function compares two 
strings only for equality, RelString compares two strings and returns a value 
indicating whether the the first string is less than, equal to, or greater than 
the second string. 


You can use the existing routine Environs to determine whether the 128K ROM is 
in use; a description of this procedure is provided below. 


When the Sound Manager is installed, the SysBeep procedure causes the alert 
sound setting specified in the Control Panel to be played. The duration 
parameter is ignored. 


Existing Macintosh applications operate in a 24-bit addressing mode. For access 
to slot card devices, the Macintosh II also supports the full 32-bit addressing 
capability of the MC68020. Two new routines, GetMMUMode and SwapMMUMode, let 
you determine, change, and restore the addressing mode, using the following 
constants: 


CONST false32b 
true32b 


0; {24-bit addressing mode} 
li {32-bit addressing mode} 


The Start Manager puts the system in 24-bit addressing mode by default. 


The 32-bit addressing mode is provided primarily so that drivers can gain full 
slot-card access. Be aware, however, that you cannot use the Memory Manager 
when in this mode, and that some Toolbox routines may not function properly. 
(Interrupt handlers will function properly in either mode. ) 


Warning: To be compatible with future versions of the Macintosh, you should 
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not depend on 24-bit addressing mode. 


A new routine, StripAddress, is correctly documented in Macintosh Technical Note 


#213. 


eeeClick on the X-Ref button, and refer to Technical Note #213.¢e¢e¢ 
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PARAMETER RAM 


Various settings, such as those specified by the user by means of the Control 
Panel desk accessory, need to be preserved when the Macintosh is off so they 
will still be present at the next system startup. This information is kept in 
parameter RAM, 20 bytes that are stored in the clock chip together with the 
current date and time setting. The clock chip is powered by a battery when the 
system is off, thereby preserving all the settings stored in it. 


You may find it necessary to read the values in parameter RAM or even change 
them (for example, if you create a desk accessory like the Control Panel). Since 
the clock chip itself is difficult to access, its contents are copied into low 
memory at system startup. You read and change parameter RAM through this low- 
memory copy. 


Note: Certain values from parameter RAM are used so frequently that special 
routines have been designed to return them (for example, the Toolbox 
Event Manager function GetDblTime). These routines are discussed in 
other chapters where appropriate. 


Assembly-language note: The low-memory copy of parameter RAM begins at the 
address SysParam; the various portions of the copy 
can be accessed through individual global variables, 
listed in the summary at the end of this chapter. 
Some of these are copied into other global variables 
at system startup for even easier access; for example, 
the auto-key threshold and rate, which are contained 
in the variable SPKbd in the copy of parameter RAM, 
are copied into the variables KeyThresh and 
KeyRepThresh. Each such variable is discussed in the 
appropriate chapter. 


The date and time setting is also copied at system startup from the clock chip 
into its own low-memory location. It's stored as a number of seconds since 
midnight, January 1, 1904, and is updated every second. The maximum value, 
$FFFFFFFF, corresponds to 6:28:15 AM, February 6, 2040; after that, it wraps 
around to midnight, January 1, 1904. 


Assembly-language note: The low-memory location containing the date and 
time is the global variable Time. 


The structure of parameter RAM is represented by the following data type: 


TYPE SysParmType = RECORD 


valid: Byte; {validity status} 

aTalkA: Byte; {AppleTalk node ID hint for modem } 
{ port} 

aTaLlkB: Byte; {AppleTalk node ID hint for printer } 
{ port} 

config: Byte; {use types for serial ports} 

porta: INTEGER; {modem port configuration} 
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portB: INTEGER; {printer port configuration} 
alarm: LONGINT; {alarm setting} 
font: INTEGER; {application font number minus 1} 
kbdPrint: INTEGER; {auto-key settings, printer } 
{ connection} 
volClik: INTEGER; {speaker volume, double-click, } 
{ caret blink} 
misc: INTEGER {mouse scaling, startup disk, } 
{ menu blink} 
END; 


SysPPtr = *“SysParmType; 


The valid field contains the validity status of the clock chip: Whenever you 
successfully write to the clock chip, $A8 is stored in this byte. The validity 
status is examined when the clock chip is read at system startup. It won't be 
$A8 if a hardware problem prevented the values from being written; in this case, 
the low-memory copy of parameter RAM is set to the default values shown in the 
table below, and these values are then written to the clock chip itself. (The 
meanings of the parameters are explained below in the descriptions of the 
various fields.) 


Parameter Default value 

Validity status $A8 

Node ID hint for modem port 0 

Node ID hint for printer port 0 

Use types for serial ports 0 (both ports) 

Modem port configuration 9600 baud, 8 data bits, 2 stop bits, 
no parity 

Printer port configuration Same as for modem port 

Alarm setting 0 (midnight, January 1, 1904) 


Application font number minus 1 2 (Geneva) 
Auto-key threshold 6 ( 

Auto-key rate 3 ( 

Printer connection 0 (printer port) 
Speaker volume 3 (medium) 
Double-click time 8 (32 ticks) 
Caret-blink time 8 (32 ticks) 

Mouse scaling 1 (on) 

Preferred system startup disk 0 (internal drive) 
Menu blink 3 


Warning: Your program must not use bits indicated below as "reserved for 
future use" in parameter RAM, since future Macintosh software 
features will use them. 


The aTalkA and aTalkB fields are used by the AppleTalk Manager; they're 
described in the manual Inside AppleTalk. 


The config field indicates which device or devices may use each of the serial 
ports; for details, see the section "Calling the AppleTalk Manager from Assembly 
Language" in the AppleTalk Manager chapter. 
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The portA and portB fields contain the baud rates, data bits, stop bits, and 
parity for the device drivers using the modem port ("port A") and printer port 
("port B"). An explanation of these terms and the exact format of the 
information are given in the Serial Drivers chapter. 


The alarm field contains the alarm setting in seconds since midnight, January 1, 
1904. 


The font field contains 1 less than the number of the application font. See the 
Font Manager chapter for a list of font numbers. 


Bit 0 of the kbdPrint field (Figure 1) designates whether the printer (if any) 
is connected to the printer port (0) or the modem port (1). Bits 8-11 of this 
field contain the auto-key rate, the rate of the repeat when a character key is 
held down; this value is stored in two-tick units. Bits 12-15 contain the auto- 
key threshold, the length of time the key must be held down before it begins to 
repeat; it's stored in four-tick units. 
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Printer connection 
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(in twotick wits] 

Auto-key threshold 
[im fowrtick wots] 


Figure 1—The F.bd Print Field 
Figure 1—The KbdPrint Field 


Bits 0-3 of the volClik field (Figure 2) contain the caret-blink time, and bits 
4-7 contain the double-click time; both values are stored in four-tick units. 
The caret-blink time is the interval between blinks of the caret that marks the 
insertion point in text. The double-click time is the greatest interval between 
a mouse-up and mouse-down event that would qualify two mouse clicks as a double- 
click. Bits 8-10 of the volClik field contain the speaker volume setting, which 
ranges from silent (@) to loud (7). 


Note: The Sound Driver procedure SetSoundVol changes the speaker volume 
without changing the setting in parameter RAM, so it's possible for 
the actual volume to be different from this setting. 


Bits 2 and 3 of the misc field (Figure 3) contain a value from 0 to 3 
designating how many times a menu item will blink when it's chosen. Bit 4 of 
this field indicates whether the preferred disk to use to start up the system is 
in the internal (0) or the external (1) drive; if there's any problem using the 
disk in the specified drive, the other drive will be used. 
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Figure 2—The VolClik Field 
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Figure 3-The Misc Field 
Figure 3—The Misc Field 


Finally, bit 6 of the misc field designates whether mouse scaling is on (1) or 
off (0). If mouse scaling is on, the system looks every sixtieth of a second at 
whether the mouse has moved; if in that time the sum of the mouse's horizontal 
and vertical changes in position is greater than the mouse-scaling threshold 
(normally six pixels), then the cursor will move twice as far horizontally and 
vertically as it would if mouse scaling were off. 


Assembly-language note: The mouse-scaling threshold is contained in the 
global variable CrsrThresh. 
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OPERATING SYSTEM QUEUES 


Some of the information used by the Operating System is stored in data 
structures called queues. A queue is a list of identically structured entries 
linked together by pointers. Queues are used to keep track of VBL tasks, I/0 
requests, events, mounted volumes, and disk drives (or other block- formatted 
devices). 


A standard Operating System queue has a header with the following structure: 


TYPE QHdr = RECORD 


qFlags: INTEGER; {queue flags} 

qHead: QElemPtr; {first queue entry} 

qlail: QElemPtr {last queue entry} 
END; 


QHdrPtr = “QHdr; 


QFlags contains information (usually flags) that's different for each queue 
type. QHead points to the first entry in the queue, and qtail points to the last 
entry in the queue. The entries within each type of queue are different; the 
Operating System uses the following variant record to access them: 


TYPE QTypes = (dummyType, 


vType, {vertical retrace queue type} 
ioQType, {file I/O or driver I/O queue type} 
drvQType, {drive queue type} 

evType, {event queue type} 

fsQType) ; {volume-control-block queue type} 


QElem = RECORD 
CASE QTypes OF 
vType: (vbLQElem: VBLTask); 


ioQType: (ioQElem: ParamBlockRec); 
drvQType: (drvQElem: DrvQEl); 
evType: (evQElem: EvQEl); 
fsQType: (vcbQElem: VCB) 

END; 


QElemPtr = *QElem; 


All entries in queues, regardless of the queue type, begin with four bytes of 
flags followed by a pointer to the next queue entry. The entries are linked 
through these pointers; each one points to the pointer field in the next entry. 
In Pascal, the data type of the pointer is QElemPtr, and the data type of the 
entry begins with the pointer field. Consequently, the flag bytes are 
inaccessible from Pascal. 


Following the pointer to the next entry, each entry contains an integer 
designating the queue type (for example, ORD(evType) for the event queue). The 
exact structure of the rest of the entry depends on the type of queue; for more 
information, see the chapter that discusses that queue in detail. 
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GENERAL OPERATING SYSTEM DATA TYPES 


This section describes two data types of general interest to users of the 
Operating System. 


There are several places in the Operating System where you specify a four- 
character sequence for something, such as for file types and application 
Signatures (described in the Finder Interface chapter). The Pascal data type for 
such sequences is 


TYPE OSType = PACKED ARRAY[1..4] OF CHAR; 
Another data type that's used frequently in the Operating System is 
TYPE OSErr = INTEGER; 


This is the data type for a result code, which many Operating System routines 
(including those described in this chapter) return in addition to their normal 
results. A result code is an integer indicating whether the routine completed 
its task successfully or was prevented by some error condition (or other special 
condition, such as reaching the end of a file). In the normal case that no error 
is detected, the result code is 


CONST noErr = 0; {no error} 


A nonzero result code (usually negative) signals an error. A list of all result 
codes is provided in Appendix A. 
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OPERATING SYSTEM UTILITY ROUTINES 


Pointer and Handle Manipulation 


These functions would be easy to duplicate with Memory Manager calls; they're 
included in the Operating System Utilities as a convenience because the 
operations they perform are so common. 


FUNCTION HandToHand (VAR theHndl: Handle) : OSErr; 


Trap macro —HandToHand 

On entry AQ: theHndl (handle) 

On exit AO: theHndl (handle) 
DO: result code (word) 


HandToHand copies the information to which theHndl is a handle and returns a new 


handle to the copy in theHndl. Since HandToHand replaces the input parameter 
with a new handle, you should retain the original value of the input parameter 
somewhere else, or you won't be able to access it. For example: 


VAR x,y: Handle; 
err: OSErr; 

y := X; 

err := HandToHand(y) 

The original handle remains in x while y becomes a different handle to an 

identical copy of the data. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


FUNCTION PtrToHand (srcPtr: Ptr; VAR dstHndl: Handle; 
size: LONGINT) : OSErr; 


Trap macro _PtrToHand 

On entry AO: srcPtr (pointer) 
DO: size (long word) 

On exit AO: dstHndl (handle) 
DO: result code (word) 


PtrToHand returns in dstHndl a newly created handle to a copy of the number of 
bytes specified by the size parameter, beginning at the location specified by 
srcPtr. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


FUNCTION PtrToXHand (srcPtr: Ptr; dstHndl: Handle; size: LONGINT) : OSErr; 
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Trap macro _PtrToXHand 

On entry AQ: srcPtr (pointer) 
Al: dstHndl (handle) 
DO: size (long word) 

On exit AO: dstHndl (handle) 
DO: result code (word) 


PtrToXHand takes the existing handle specified by dstHndl and makes it a handle 
to a copy of the number of bytes specified by the size parameter, beginning at 
the location specified by srcPtr. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


FUNCTION HandAndHand (aHndl,bHndl: Handle) : OSErr; 


Trap macro —HandAndHand 
On entry AO: aHndl (handle) 
Al: bHndl (handle) 
On exit AO: bHndl (handle) 
DO: result code (word) 


HandAndHand concatenates the information to which aHndl is a handle onto the end 
of the information to which bHndl is a handle. 


Warning: HandAndHand dereferences aHndl, so be sure to call the Memory 
Manager procedure HLock to lock the block before calling HandAndHand. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


FUNCTION PtrAndHand (pntr: Ptr; hndl: Handle; size: LONGINT) : OSErr; 


Trap macro —_PtrAndHand 
On entry AQ: pntr (pointer) 

Al: hndl (handle) 

DO: size (long word) 
On exit AO: hndl (handle) 

DO: result code (word) 


PtrAndHand takes the number of bytes specified by the size parameter, beginning 
at the location specified by pntr, and concatenates them onto the end of the 
information to which hndl is a handle. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 
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String Comparison 


Assembly-language note: The trap macros for these utility routines have 
optional arguments corresponding to the Pascal flags 
passed to the routines. When present, such an argument 
sets a certain bit of the routine trap word; this is 
equivalent to setting the corresponding Pascal flag to 
either TRUE or FALSE, depending on the flag. The trap 
macros for these routines are listed with all the 
possible permutations of arguments. Whichever 
permutation you use, you must type it exactly as shown. 
(The syntax shown applies to the Lisa Workshop 
Assembler; programmers using another development 
system should consult its documentation for the proper 
syntax. ) 


FUNCTION EqualString (aStr,bStr: Str255; 
caseSens,diacSens: BOOLEAN) : BOOLEAN; 


Trap macro CmpString 


_CmpString ,MARKS (sets bit 9, for diacSens=FALSE) 
_CmpString ,CASE (sets bit 10, for caseSens=TRUE) 
_CmpString ,MARKS,CASE (sets bits 9 and 10) 
On entry AO: pointer to first character of first string 
Al: pointer to first character of second string 
DO: high-order word: length of first string 
low-order word: length of second string 
On exit DO: 0 if strings equal, 1 if strings not equal (long word) 


EqualString compares the two given strings for equality on the basis of their 
ASCII values. If caseSens is TRUE, uppercase characters are distinguished from 
the corresponding lowercase characters. If diacSens is FALSE, diacritical marks 
are ignored during the comparison. The function returns TRUE if the strings are 
equal. 


Note: See also the International Utilities Package function IUEqualString. 
FUNCTION RelString (aStr,bStr: Str255; caseSens,diacSens: BOOLEAN) : INTEGER; 
RelString is similar to EqualString except that it indicates whether the first 
string is less than, equal to, or greater than the second string by returning 


either —-1, 0, or 1 respectively. 


Trap macro _RelString 


_RelString ,MARKS (sets bit 9, for diacSens=FALSE) 
_RelString ,CASE (sets bit 10, for caseSens=TRUE) 
_RelString ,MARKS,CASE (sets bits 9 and 10) 

On entry AQ: pointer to first character of first string 


Al: pointer to first character of second string 
DO: high-order word: length of first string 
low-order word: length of second string 
On exit DO: -1 if first string less than second, 0 if equal, 
1 if first string greater than second (long word) 
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RelString follows the sort order described in the International Utilities 
Package chapter except for the reordering of the following ligatures: 


& falls between A and 
z falls between @4 and 
€ falls between @ 
ce falls between @ and 
& falls between s 


fe)) 

= 

[ou 
Avo WY 


If diacSens is FALSE, diacritical marks are ignored; RelString strips 
table: 


diacriticals according to the following 
A ea A, A, A, A 
C <-- ¢ 
E <-- E 
N <-- N | 
0 <-- 0, 0, @ 
U <-- U 
a ite decay de Oyo, aes 
Cc <-- C 
e <-- é, e, 6, é 
i <-- i, i, i, i 
n <-- A 
re) <-- 6, 0, 6, 6, 6, @, 2 
U <-- u, u, a, U 
y S55 y 


Note: This stripping is identical to that performed by the UprString 
procedure when the diacSens parameter is FALSE. 


If caseSens is FALSE, the comparison is not case-sensitive; RelString performs a 
conversion from lower-case to upper-case characters according to the following 


table: 

A <-- a 
wee Se 

Z <-- Z 
A <- a 
A <- 4 
A <-- a 
A ea a 
E <-- #e 
a 
E <- é 
N <-- A 
OQ <- 46 
0 <-- e) 
g <-- i) 
€ <- @ 
U <-- U 


Note: This conversion is identical to that performed by the UprString 


procedure. 


PROCEDURE UprString (VAR theString: Str255; diacSens: 


BOOLEAN) ; 
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Trap macro UprString 
_UprString ,MARKS (sets bit 9, for diacSens=FALSE) 


On entry AQ: pointer to first character of string 
DO: length of string (word) 
On exit AQ: pointer to first character of string 


UprString converts any lowercase letters in the given string to uppercase, 
returning the converted string in theString. In addition, diacritical marks are 
stripped from the string if diacSens is FALSE. 


Date and Time Operations 


The following utilities are for reading and setting the date and time stored in 
the clock chip. Reading the date and time is a fairly common operation; setting 
it is somewhat rarer, but could be necessary for implementing a desk accessory 
like the Control Panel. 


The date and time setting is stored as an unsigned number of seconds since 
midnight, January 1, 1904; you can use a utility routine to convert this to a 
date/time record. Date/time records are defined as follows: 


TYPE DateTimeRec = RECORD 


year: INTEGER; {1904 to 2040} 

month: INTEGER; {1 to 12 for January to December} 

day: INTEGER; {1 to 31} 

hour: INTEGER; {0 to 23} 

minute: INTEGER; {0 to 59} 

second: INTEGER; {0 to 59} 

dayOfWeek: INTEGER {1 to 7 for Sunday to Saturday} 
END; 


FUNCTION ReadDateTime (VAR secs: LONGINT) : OSErr; 


Trap macro _ReadDateTime 

On entry AQ: pointer to long word secs 

On exit AQ: pointer to long word secs 
DO: result code (word) 


ReadDateTime copies the date and time stored in the clock chip to a low-memory 
location and returns it in the secs parameter. This routine is called at system 
startup; you'll probably never need to call it yourself. Instead you'll call 
GetDateTime (see below). 


Assembly-language note: The low-memory location to which ReadDateTime 
copies the date and time is the global variable Time. 


Result codes noErr No error 
clkRdErr Unable to read clock 


PROCEDURE GetDateTime (VAR secs: LONGINT); [Not in ROM] 
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GetDateTime returns in the secs parameter the contents of the low-memory 
location in which the date and time setting is stored; if this setting reflects 
the actual current date and time, secs will contain the number of seconds 
between midnight, January 1, 1904 and the time that the function was called. 


Note: If your application disables interrupts for longer than a second, 
the number of seconds returned will not be exact. 


Assembly-language note: Assembly-language programmers can just access 
the global variable Time. 


If you wish, you can convert the value returned by GetDateTime to a date/time 
record by calling the Secs2Date procedure. 


Note: Passing the value returned by GetDateTime to the International 
Utilities Package procedure IUDateString or IUTimeString will yield 
a string representing the corresponding date or time of day, 
respectively. 


FUNCTION SetDateTime (secs: LONGINT) : OSErr; 


Trap macro _SetDateTime 
On entry DO: secs (long word) 
On exit DO: result code (word) 


SetDateTime takes a number of seconds since midnight, January 1, 1904, as 
specified by the secs parameter, and writes it to the clock chip as the current 
date and time. It then attempts to read the value just written and verify it by 
comparing it to the secs parameter. 


Assembly-language note: SetDateTime updates the global variable Time to 
the value of the secs parameter. 


Result codes noErr No error 
clkWrErr Time written did not verify 
clkRdErr Unable to read clock 


PROCEDURE Date2Secs (date: DateTimeRec; VAR secs: LONGINT); 


Trap macro Date2Secs 
On entry AQ: pointer to date/time record 
On exit DO: secs (long word) 


Date2Secs takes the given date/time record, converts it to the corresponding 
number of seconds elapsed since midnight, January 1, 1904, and returns the 
result in the secs parameter. The dayOfWeek field of the date/time record is 
ignored. The values passed in the year and month fields should be within their 
allowable ranges, or unpredictable results will occur. The remaining four fields 
of the date/time record may contain any value. For example, September 34 will be 
interpreted as October 4, and you could specify the 300th day of the year as 
January 300. 


PROCEDURE Secs2Date (secs: LONGINT; VAR date: DateTimeRec); 


Trap macro Secs2Date 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE OPERATING SYSTEM UTILITIES ¢e 15 of 29 


On entry DO: secs (long word) 
On exit AQ: pointer to date/time record 


Secs2Date takes a number of seconds elapsed since midnight, January 1, 1904 as 
specified by the secs parameter, converts it to the corresponding date and time, 
and returns the corresponding date/time record in the date parameter.PROCEDURE 
GetTime (VAR date: DateTimeRec); [Not in ROM] 


GetTime takes the number of seconds elapsed since midnight, January 1, 1904 
(obtained by calling GetDateTime), converts that value into a date and time (by 
calling Secs2Date), and returns the result in the date parameter. 


Assembly-language note: From assembly language, you can pass the value 
of the global variable Time to Secs2Date. 


PROCEDURE SetTime (date: DateTimeRec); [Not in ROM] 


SetTime takes the date and time specified by the date parameter, converts it 
into the corresponding number of seconds elapsed since midnight, January 1, 1904 
(by calling Date2Secs), and then writes that value to the clock chip as the 
current date and time (by calling SetDateTime). 


Assembly-language note: From assembly language, you can just call Date2Secs 
and SetDateTime directly. 


Parameter RAM Operations 

The following three utilities are used for reading from and writing to parameter 
RAM. Figure 4 illustrates the function of these three utilities; further details 
are given below and in the "Parameter RAM" section. 

FUNCTION InitUtil : OSErr; 


Trap macro —_InitUtil 
On exit DO: result code (word) 
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Figure 4-—Parameter RAM Routines 


Figure 4—Parameter RAM Routines 


InitUtil copies the contents of parameter RAM into 20 bytes of low memory and 
copies the date and time from the clock chip into its own low-memory Location. 
This routine is called at system startup; you'll probably never need to call it 
yourself. 


Assembly-language note: InitUtil copies parameter RAM into 20 bytes starting 
at the address SysParam and copies the date and time 
into the global variable Time. 


If the validity status in parameter RAM is not $A8 when InitUtil is called, an 
error is returned as the result code, and the default values (given in the 
"Parameter RAM" section) are read into the low-memory copy of parameter RAM; 
these values are then written to the clock chip itself. 


Result codes noErr No error 
prinitErr Validity status not $A8 


FUNCTION GetSysPPtr : SysPPtr; [Not in ROM] 


GetSysPPtr returns a pointer to the low-memory copy of parameter RAM. You can 
examine the values stored in its various fields, or change them before calling 
WriteParam (below). 


Assembly-language note: Assembly-language programmers can simply access the 
global variables corresponding to the low-memory copy 
of parameter RAM. These variables, which begin at the 
address SysParam, are listed in the summary. 


FUNCTION WriteParam : OSErr; 


Trap macro WriteParam 
On entry AO: SysParam (pointer) 
DO: MinusOne (long word) 
(You have to pass the values of these global variables for 
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historical reasons.) 
On exit DO: result code (word) 


WriteParam writes the low-memory copy of parameter RAM to the clock chip. You 
should previously have called GetSysPPtr and changed selected values as desired. 


WriteParam also attempts to verify the values written by reading them back in 
and comparing them to the values in the low-memory copy. 


Note: If you've accidentally written incorrect values into parameter RAM, 
the system may not be able to start up. If this happens, you can reset 
parameter RAM by removing the battery, letting the Macintosh sit turned 
off for about five minutes, and then putting the battery back in. 


Result codes noErr No error 
prwrErr Parameter RAM written did not verify 


Queue Manipulation 


This section describes utilities that advanced programmers may want to use for 
adding entries to or deleting entries from an Operating System queue. Normally 
you won't need to use these utilities, since queues are manipulated for you as 
necessary by routines that need to deal with them. 


PROCEDURE Enqueue (gEntry: QElemPtr; theQueue: QHdrPtr); 


Trap macro —Enqueue 

On entry AQ: qEntry (pointer) 
Al: theQueue (pointer) 

On exit Al: theQueue (pointer) 


Enqueue adds the queue entry pointed to by gEntry to the end of the queue 
specified by theQueue. 


Note: Interrupts are disabled for a short time while the queue is updated. 
FUNCTION Dequeue (qEntry: QElemPtr; theQueue: QHdrPtr) : OSErr; 


Trap macro —_Dequeue 

On entry AQ: qEntry (pointer) 
Al: theQueue (pointer) 

On exit Al: theQueue (pointer) 
DO: result code (word) 


Dequeue removes the queue entry pointed to by gEntry from the queue specified by 
theQueue (without deallocating the entry) and adjusts other entries in the queue 
accordingly. 


Note: The note under Enqueue above also applies here. In this case, the 
amount of time interrupts are disabled depends on the length of the 
queue and the position of the entry in the queue. 


Note: To remove all entries from a queue, you can just clear all the fields 
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of the queue's header. 


Result codes noErr No error 
gErr Entry not in specified queue 


Trap Dispatch Table Utilities 


The Operating System Utilities include two routines for manipulating the trap 
dispatch table, which is described in detail in the Using Assembly Language 
chapter. Using these routines, you can intercept calls to an Operating System or 
Toolbox routine and do some pre- or post-processing of your own: Call 
GetTrapAddress to get the address of the original routine, save that address for 
later use, and call SetTrapAddress to install your own version of the routine in 
the dispatch table. Before or after its own processing, the new version of the 
routine can use the saved address to call the original version. 


Warning: You can replace as well as intercept existing routines; in any case, 
you should be absolutely sure you know what you're doing. Remember 
that some calls that aren't in ROM do some processing of their own 
before invoking a trap macro (for example, FSOpen eventually invokes 
Open, and IUCompString invokes the macro for IUMagString). Also, a 
number of ROM routines have been patched with corrected versions in 
RAM; if you intercept a patched routine, you must not do any 
processing after the existing patch, and you must be sure to 
preserve the registers and the stack (or the system won't work 
properly). 


Assembly-language note: You can tell whether a routine is patched by comparing 
its address to the global variable ROMBase; if the 
address is less than ROMBase, the routine is patched. 


In addition, you can use GetTrapAddress to save time in critical sections of 
your program by calling an Operating System or Toolbox routine directly, 
avoiding the overhead of a normal trap dispatch. 


FUNCTION GetTrapAddress (trapNum: INTEGER) : LONGINT; 


Trap macro _GetTrapAddress 
On entry DO: trapNum (word) 
On exit AO: address of routine 


GetTrapAddress returns the address of a routine currently installed in the trap 
dispatch table under the trap number designated by trapNum. To find out the trap 
number for a particular routine, see Appendix C. 


Assembly-language note: When you use this technique to bypass the trap 
dispatcher, you don't get the extra level of register 
saving. The routine itself will preserve A2-A6 and 
D3-D7, but if you want any other registers preserved 
across the call you have to save and restore them 
yourself. 


PROCEDURE SetTrapAddress (trapAddr: LONGINT; trapNum: INTEGER); 
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Trap macro _SetTrapAddress 
On entry AQ: trapAddr (address) 
DO: trapNum (word) 


SetTrapAddress installs in the trap dispatch table a routine whose address is 
trapAddr; this routine is installed under the trap number designated by trapNum. 


Warning: Since the trap dispatch table can address locations within a range 
of only 64K bytes from the beginning of the system heap, the routine 
you install should be in the system heap. 


Assembly-language note: To use GetTrapAddress and SetTrapAddress with 
128K ROM routines, set bit 9 of the trap word to 
indicate the new trap numbering. The state of bit 
10 then determines whether the intended trap is a 
Toolbox or Operating System trap. You can set these 
two bits with the arguments NEWOS and NEWTOOL. 


Of course, the 64K ROM versions of GetTrapAddress and 
SetTrapAddress will fail if applied to traps that 
exist only in the 128K ROM. 


The NGetTrapAddress and NSetTrapAddress routines list 
the possible permutations of arguments. (The syntax 
shown applies to the Lisa Workshop Assembler; 
programmers using another development system should 
consult its documentation for the proper syntax. ) 


FUNCTION NGetTrapAddress (trapNum: INTEGER; tType: TrapType) : LongInt; 
[Not in ROM] 


NGetTrapAddress is identical to GetTrapAddress except that it requires you to 
specify in tType whether the given routine is an Operating System or a Toolbox 
trap. 


Trap macro _GetTrapAddress ,NEWOS (bit 9 set, bit 10 clear) 
_GetTrapAddress ,NEWTOOL (bit 9 set, bit 10 set) 

On entry DO: trapNum (word) 

On exit AQ: address of routine 


PROCEDURE NSetTrapAddress (trapAddr: LongInt; trapNum: INTEGER; 
tType: TrapType); [Not in ROM] 


NSetTrapAddress is identical to SetTrapAddress except that it requires you to 
specify in tType whether the given routine is an Operating System or a Toolbox 
trap. 


Trap macro SetTrapAddress ,NEWOS (bit 9 set, bit 10 clear) 
_SetTrapAddress ,NEWTOOL (bit 9 set, bit 10 set) 
On entry AQ: trapAddr (address) 
DO: trapNum (word) 
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Miscellaneous Utilities 
PROCEDURE Delay (numTicks: LONGINT; VAR finalTicks: LONGINT); 


Trap macro Delay 
On entry AQ: numTicks (long word) 
On exit DO: finalTicks (long word) 


Delay causes the system to wait for the number of ticks (sixtieths of a second) 
specified by numTicks, and returns in finalTicks the total number of ticks from 
system startup to the end of the delay. 


Warning: Don't rely on the duration of the delay being exact; it will usually 
be accurate to within one tick, but may be off by more than that. 
The Delay procedure enables all interrupts and checks the tick count 
that's incremented during the vertical retrace interrupt; however, 
it's possible for this interrupt to be disabled by other interrupts, 
in which case the duration of the delay will not be exactly what you 
requested. 


Assembly-language note: On exit from this procedure, register DO contains the 
value of the global variable Ticks as measured at the 
end of the delay. 


PROCEDURE SysBeep (duration: INTEGER); 


SysBeep causes the system to beep for approximately the number of ticks 
specified by the duration parameter. The sound decays from loud to soft; after 
about five seconds it's inaudible. The initial volume of the beep depends on the 
current speaker volume setting, which the user can adjust with the Control Panel 
desk accessory. If the speaker volume has been set to 0 (silent), SysBeep 
instead causes the menu bar to blink once. 


Assembly-language note: Unlike all other Operating System Utilities, this 
procedure is stack-based. 


PROCEDURE Environs (VAR rom,machine: INTEGER) [Not in ROM] 


In the rom parameter, Environs returns the current ROM version number (for a 
Macintosh XL, the version number of the ROM image installed by MacWorks). To use 
the 128K ROM information described in this volume, the version number should be 
greater than or equal to 117 ($75). In the machine parameter, Environs returns 
an indication of which machine is in use, as follows: 


CONST macXLMachine 
macMachine 


0; {Macintosh XL} 
1; {Macintosh 128K, 512K, 512K upgraded, } 
{ 512K enhanced, or Macintosh Plus} 


Note: The machine parameter does not distinguish between the Macintosh 128K, 
512K, 512K upgraded, 512K enhanced, and Macintosh Plus. 


Assembly-language note: From assembly language, you can get this information 
from the word that's at an offset of 8 from the 
beginning of ROM (which is stored in the global 
variable ROMBase). The format of this word is $00xx 
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for the Macintosh 128K, 512K, 512K enhanced, or 
Macintosh Plus, and $xxFF for the Macintosh XL, where 
Xx is the ROM version number. (The ROM version number 
will always be between $01 and $FE.) 


PROCEDURE Restart; [Not in ROM] 
This procedure restarts the system. 


Assembly-language note: From assembly language, you can give the following 
instructions to restart the system: 


MOVE.L ROMBase, AO 
JMP $0A (AO) 


Note: The procedures SetUpA5 and RestoreA5 were formerly documented in this 
chapter; however, two routines with more functionality are now available 
with the MPW 3.0 and later libraries. The routines SetCurrentA5 and 
SetA5 are documented in Macintosh Technical Note #208. 

eeeClick on the X-Ref button, and refer to Technical Note #208. +¢: 

FUNCTION GetMMUMode (VAR mode: INTEGER); [Not in ROM] 

GetMMUMode returns the address translation mode currently in use. 

Assembly-language note: Assembly-language programmers can determine the 

current address mode by testing the contents of 
the global variable MMU32Bit; it's TRUE if 32-bit 
mode is in effect. 

eeeClick on the X-Ref button, and refer to Technical Note #228. +e: 

PROCEDURE SwapMMUMode (VAR mode: Byte); 

Trap macro —SwapMMUMode 

On entry DO: mode (byte) 

On exit DO: mode (byte) 

SwapMMUMode sets the address translation mode to that specified by the mode 

parameter. The mode in use prior to the call is returned in mode, and can be 

restored with another call to SwapMMUMode. 

FUNCTION StripAddress (theAddress: Ptr) : Ptr; 

Trap macro _StripAddress 

On entry DO: theAddress (pointer) 

On exit DO: function result (pointer) 


The original description of StripAddress was incorrect. Technical Note #213 
correctly documents this function. 


eeeClick on the X-Ref button, and refer to Technical Note #213.¢e¢e 
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SUMMARY OF THE OPERATING SYSTEM UTILITIES 


Constants 


CONST 


{ Values returned by Environs procedure } 


macXLMachine 
macMachine 


0; {Macintosh XL} 
1 


: {Macintosh 128K, 512K, 512K upgraded, } 


{ 512K enhanced, or Macintosh Plus} 


{ Result codes } 


clkRdErr 
clkWrErr 
memFullErr 
memWZErr 
nilHandleErr 
noErr 
prinitErr 
prWrErr 

gErr 


0 {no error} 


{ Addressing modes } 


-85; {unable to read clock} 

-86; {time written did not verify} 
-108; {not enough room in heap zone} 
-111; {attempt to operate on a free block} 
-109; {NIL master pointer} 


-88; {validity status is not $A8} 
-87; {parameter RAM written did not verify} 
-1 fentry not in specified queue} 


false32b = 0; {24-bit addressing mode} 
true32b =e." {32-bit addressing mode} 
Data Types 
TYPE 
OSType = PACKED ARRAY[1..4] OF CHAR; 
OSErr = INTEGER; 
SysPPtr = “SysParmType; 
SysParmType = RECORD 
valid: Byte; {validity status} 
aTalkA: Byte; {AppleTalk node ID hint for modem } 
{ port} 
aTalkB: Byte; {AppleTalk node ID hint for printer } 
{ port} 
config: Byte; {use types for serial ports} 
porta: INTEGER; {modem port configuration} 
portB: INTEGER; {printer port configuration} 
alarm: LONGINT; {alarm setting} 
font: INTEGER; {application font number minus 1} 


kbdPrint: INTEGER; 


f{auto-key settings, printer } 
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{ connection} 


volClik: INTEGER; {speaker volume, double-click, } 
{ caret blink} 
misc: INTEGER {mouse scaling, startup disk, } 
{ menu blink} 
END; 
QHdrPtr = *QHdr; 
QHdr = RECORD 
qFlags: INTEGER; {queue flags} 
qHead: QElemPtr; {first queue entry} 
qtail: QElemPtr {last queue entry} 
END; 
QTypes = (dummyType, 
vType, {vertical retrace queue type} 
ioQType, {file I/O or driver I/O queue type} 
drvQType, {drive queue type} 
evType, {event queue type} 
fsQType) ; {volume-control-block queue type} 
QElemPtr = *QElem; 
QElem = RECORD 
CASE QTypes OF 
vType: (vbLQElem: VBLTask); 
ioQType: (i0QElem: ParamBlockRec) ; 
drvQType: (drvQElem: DrvQEl); 
evType: (evQElem: EvQEl); 
fsQType: (vcbQElem: VCB) 
END; 
DateTimeRec = RECORD 
year: INTEGER; {1904 to 2040} 
month: INTEGER; {1 to 12 for January to December} 
day: INTEGER; {1 to 31} 
hour: INTEGER; {0 to 23} 
minute: INTEGER; {0 to 59} 
second: INTEGER; {0 to 59} 
dayOfWeek: INTEGER {1 to 7 for Sunday to Saturday} 
END; 
TrapType = (OSTrap,ToolTrap) ; 
Routines 


Pointer and Handle Manipulation 


FUNCTION HandToHand (VAR theHndl: Handle) OSErr; 

FUNCTION PtrToHand (srcPtr: Ptr; VAR dstHndl: Handle; 
size: LONGINT) OSErr; 

FUNCTION PtrToXHand (srcPtr: Ptr; dstHndl: Handle; 
size: LONGINT) OSErr; 

FUNCTION HandAndHand (aHndl,bHndl: Handle) OSErr; 
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OP 


FUNCTION PtrAndHand (pntr: Ptr; hndl: Handle; size: LONGINT) : OSErr; 


String Comparison 


FUNCTION EqualString (aStr,bStr: Str255; 

caseSens,diacSens: BOOLEAN) : BOOLEAN; 
FUNCTION RelString (aStr,bStr: Str255; 

caseSens,diacSens: BOOLEAN) : INTEGER; 
PROCEDURE UprString (VAR theString: Str255; diacSens: BOOLEAN); 
Date and Time Operations 
FUNCTION ReadDateTime (VAR secs: LONGINT) : OSErr; 
PROCEDURE GetDateTime (VAR secs: LONGINT); [Not in ROM] 
FUNCTION SetDateTime (secs: LONGINT) : OSErr; 
PROCEDURE Date2Secs (date: DateTimeRec; VAR secs: LONGINT); 
PROCEDURE Secs2Date (secs: LONGINT; VAR date: DateTimeRec); 
PROCEDURE GetTime (VAR date: DateTimeRec); [Not in ROM] 
PROCEDURE SetTime (date: DateTimeRec); [Not in ROM] 


Parameter RAM Operations 


FUNCTION InitUtil : OSErr; 
FUNCTION GetSysPPtr : SysPPtr; [Not in ROM] 
FUNCTION WriteParam : OSErr; 


Queue Manipulation 


PROCEDURE Enqueue (gEntry: QElemPtr; theQueue: QHdrPtr); 
FUNCTION Dequeue (gEntry: QElemPtr; theQueue: QHdrPtr) : OSErr; 


Trap Dispatch Table Utilities 


PROCEDURE SetTrapAddress (trapAddr: LONGINT; trapNum: INTEGER); 
FUNCTION GetTrapAddress (trapNum: INTEGER) : LONGINT; 
FUNCTION NGetTrapAddress (trapNum: INTEGER; 
tType: TrapType) : LongInt; [Not in ROM] 
PROCEDURE NSetTrapAddress (trapAddr: LongInt; trapNum: INTEGER; 
tType: TrapType); [Not in ROM] 


Miscellaneous Utilities 


PROCEDURE Delay (numTicks: LONGINT; VAR finalTicks: LONGINT); 
PROCEDURE SysBeep (duration: INTEGER); 

PROCEDURE Environs (VAR rom,machine: INTEGER) [Not in ROM] 
PROCEDURE Restart; [Not in ROM] 

PROCEDURE GetMMUMode (VAR mode: Byte); 

PROCEDURE SwapMMUMode (VAR mode: Byte); 

FUNCTION StripAddress (theAddress: LONGINT) : LONGINT; 


Default Parameter RAM Values 
Parameter Default value 


Validity status $A8 
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Node ID hint for modem port 
Node ID hint for printer port 
Use types for serial ports 
Modem port configuration 


Printer port configuration 


0 

0 

0 (both ports) 

9600 baud, 8 data bits, 2 stop bits, 
no parity 

Same as for modem port 


Alarm setting 0 (midnight, January 1, 1904) 
Application font number minus 1 2 (Geneva) 

Auto-key threshold 6 (24 ticks) 

Auto-key rate 3 (6 ticks) 

Printer connection 0 (printer port) 

Speaker volume 3 (medium) 

Double-click time 8 (32 ticks) 

Caret-blink time 8 (32 ticks) 

Mouse scaling 1 (on) 

Preferred system startup disk 0 (internal drive) 

Menu blink 3 

Assembly-Language Information 

Constants 

; Result codes 

clkRdErr . EQU -85 ;unable to read clock 

clkWrErr . EQU —86 ;time written did not verify 
memFullErr .EQU  -—108 ;not enough room in heap zone 
memWZErr .-EQU -111 ;attempt to operate on a free block 
nilHandleErr .EQU  -109 ;NIL master pointer 

noErr . EQU 0 ;no error 

priniteErr .EQU —88 ;validity status is not $A8 
prwrErr .EQU -87 ;parameter RAM written did not verify 
gErr . EQU -1 ;entry not in specified queue 

; Addressing modes 

false32b .EQU 0 ;24-bit addressing mode 

true32b .EQU 1 ;32-bit addressing mode 


; Queue types 


vType .EQU 1 
ioQType . EQU 2 
drvQType . EQU 3 
evType . EQU 4 
fsQType . EQU 5 


Queue Data Structure 


qFlags Queue flags (word) 


;vertical retrace queue type 

;file I/0 or driver I/0 queue type 
;drive queue type 

;event queue type 
;volume-control-block queue type 


qHead Pointer to first queue entry 
qrail Pointer to last queue entry 
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Date/Time Record Data Structure 


dtYear 1904 to 2040 (word) 

dtMonth 1 to 12 for January to December (word) 

dtDay 1 to 31 (word) 

dtHour 0 to 23 (word) 

dtMinute 0 to 59 (word) 

dtSecond 0 to 59 (word) 

dtDay0 fWeek 1 to 7 for Sunday to Saturday (word) 

Routines 

Trap macro On entry On exit 

_HandToHand AO: theHndl (handle) AO: theHndl (handle) 

DO: result code(word) 

_PtrToHand AO: srcPtr (ptr) AO: dstHndl (handle) 
DO: size (long) DO: result code (word) 

_PtrToXHand AO: srcPtr (ptr) AO: dstHndl (handle) 
Al: dstHndl (handle) DO: result code (word) 
DO: size (long) 

_HandAndHand AO: aHndl (handle) AO: bHndl (handle) 
Al: bHndl (handle) DO: result code (word) 

_PtrAndHand AQ: pntr (ptr) AQ: hndl (handle) 
Al: hndl (handle) DO: result code (word) 
DO: size (long) 

_CmpString _CmpString ,MARKS sets bit 9, for diacSens=FALSE 


_CmpString ,CASE sets bit 10, for caseSens=TRUE 
_CmpString ,MARKS,CASE sets bits 9 and 10 
AQ: ptr to first string DO: O if equal, 1 if 
Al: ptr to second string not equal (long) 
DO: high word: length of 
first string 
low word: Length of 
second string 
_RelString _RelString ,MARKS 
(sets bit 9, for diacSens=FALSE) 
_RelString ,CASE 
(sets bit 10, for caseSens=TRUE) 
_RelString ,MARKS, CASE 
(sets bits 9 and 10) 


AQ: ptr to first string DO: -1 if first less than 
Al: ptr to second string second, 0 if equal, 1 if 
DO: high word: length of first greater than 

first string second (long) 


low word: Length of 
second string 


_UprString _UprString ,MARKS sets bit 9, for diacSens=FALSE 

AQ: ptr to string AQ: ptr to string 

DO: length of string (word) 
_ReadDateTime AQ: ptr to long word secs AQ: ptr to long word secs 

DO: result code (word) 

_SetDateTime DO: secs (long) DO: result code (word) 
_Date2Secs AQ: ptr to date/time record DQ: secs (long) 
_Secs2Date DO: secs (long) AO: ptr to date/time record 
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_Initutil 


DO: result code (word) 


_WriteParam AO: SysParam (ptr) DO: result code (word) 
DO: MinusOne (long) 
_Enqueue AQ: qEntry (ptr) Al: theQueue (ptr) 
Al: theQueue (ptr) 
_Dequeue AQ: qEntry (ptr) Al: theQueue (ptr) 
Al: theQueue (ptr) DO: result code (word) 
_GetTrapAddress _GetTrapAddress ,NEWOS 
(bit 9 set, bit 10 clear) 
_GetTrapAddress ,NEWTOOL 
(bit 9 set, bit 10 set) 
DO: trapNum (word) AQ: address of routine 
_SetTrapAddress _SetTrapAddress ,NEWOS 
(bit 9 set, bit 10 clear) 
_SetTrapAddress ,NEWTOOL 
(bit 9 set, bit 10 set) 
AQ: trapAddr (address) 
DO: trapNum (word) 
_Delay AQ: numTicks (long) DO: finalTicks (long) 
_SysBeep stack: duration (word) 
_SwapMMUMode DO: mode (byte) DO: mode (byte) 
_StripAddress DO: the Address (long) DO: function result (long) 
Variables 
SysParam Low-memory copy of parameter RAM (20 bytes) 
SPValid Validity status (byte) 
SPATalkA AppleTalk node ID hint for modem port (byte) 
SPATaLkB AppleTalk node ID hint for printer port (byte) 
SPConfig Use types for serial ports (byte) 
SPPortA Modem port configuration (word) 
SPPortB Printer port configuration (word) 
SPALarm Alarm setting (long) 
SPFont Application font number minus 1 (word) 
SPKbd Auto-key threshold and rate (byte) 
SPPrint Printer connection (byte) 
SPVoLCtl Speaker volume (byte) 
SPClLikCaret Double-click and caret-blink times (byte) 
SPMisc2 Mouse scaling, system startup disk, menu blink (byte) 
CrsrThresh Mouse-scaling threshold (word) 
Time Seconds since midnight, January 1, 1904 (long) 
ROMBase Base address of ROM 
MMU32Bit Current address mode (byte) 
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Further Reference: 


Technical 
Technical 
Technical 
Technical 
Technical 
Technical 
Technical 


Note #25, Don't Depend on Register A5 Within Trap Patches 
Note #156, Checking for Specific Functionality 


Note #184, Notification Manager 
Note #208, Setting and Restoring A5 


Note #213, StripAddress: The Untold Story 
Note #228, Use Care When Swapping MMU Mode 


Note #261, Cache As Cache Can 


END OF DOCUMENT 
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